Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Doc improvements #1184

Merged
merged 7 commits into from
May 18, 2020
Merged

Doc improvements #1184

merged 7 commits into from
May 18, 2020

Conversation

OriolAbril
Copy link
Member

@OriolAbril OriolAbril commented May 14, 2020 •
edited
Loading

Description

This PR adds several new features to docs. Some of them are a not very well documented so I'll try to add this to the developer guide so we can make the most of these improvements.

Using see also

The see also section can also be used and links are generated automatically by sphinx. See compare for one example. We have to modify the css file to change the color, otherwise it is hardly readable. Any help would be greatly appreciated.

Referencing methods in other libraries

For now, xarray and pymc3 are configured to make it easy to reference their docs. This is possible thanks to intersphinx. Therefore, rst code such as:

:func:`pymc3:pymc3.sampling.sample`
:meth:`xarray.Dataset.sel <xarray:xarray.Dataset.sel>`  # example of modifying link text

Will directly link to the corresponding docs, see from_pymc3 and InferenceData.sel. The initial part is quite tricky, depending on what is referenced it has to be one or another key. The accepted keys can be found here, however in some cases it can be hard to guess. In such cases, the sphobjinv package can come in handy. It can search the documentation for us and return the interesting objects to tag:

$ sphobjinv suggest -t 90 -u https://docs.pymc.io/objects.inv "sampling.sample"
 
Remote inventory found.
 
:py:function:`pymc3.sampling.sample`
:py:function:`pymc3.sampling.sample_posterior_predictive`
:py:function:`pymc3.sampling.sample_posterior_predictive_w`
:py:function:`pymc3.sampling.sample_ppc`
:py:function:`pymc3.sampling.sample_ppc_w`
:py:function:`pymc3.sampling.sample_prior_predictive`
:std:label:`/api/inference.rst#pymc3.sampling.sample`
:std:label:`/api/inference.rst#pymc3.sampling.sample_posterior_predictive`
:std:label:`/api/inference.rst#pymc3.sampling.sample_posterior_predictive_w`
:std:label:`/api/inference.rst#pymc3.sampling.sample_ppc`
:std:label:`/api/inference.rst#pymc3.sampling.sample_ppc_w`
:std:label:`/api/inference.rst#pymc3.sampling.sample_prior_predictive`

The codes still have to be updated from :py:function: to :py:func: to follow match the accepted keys, see link above.

Referencing ArviZ functions

Same thing as above can be used: :py:func: and similar keywords.

Other

Several formatting fixes to reduce warnings and make sure all plots in docstring are correctly generated and updating from m2r to recommonmark to convert markdown to rst. Now everything should be sphinx3 compatible. Everything is now sphinx3 compatible.

Checklist

  • Follows official PR format
  • New features documented in the developer guide
  • Code style correct (follows pylint and black guidelines)
  • Changes are listed in changelog

@codecov
Copy link

codecov bot commented May 14, 2020 •
edited
Loading

Codecov Report

Merging #1184 into master will not change coverage.
The diff coverage is n/a.

Impacted file tree graph

@@           Coverage Diff           @@
##           master    #1184   +/-   ##
=======================================
  Coverage   93.12%   93.12%           
=======================================
  Files          94       94           
  Lines        9351     9351           
=======================================
  Hits         8708     8708           
  Misses        643      643
Impacted Files Coverage Δ
arviz/data/inference_data.py 81.88% <ø> (ø)
arviz/data/io_cmdstan.py 94.84% <ø> (ø)
arviz/data/io_cmdstanpy.py 100.00% <ø> (ø)
arviz/data/io_dict.py 89.89% <ø> (ø)
arviz/data/io_numpyro.py 95.23% <ø> (ø)
arviz/data/io_pymc3.py 92.74% <ø> (ø)
arviz/data/io_pyro.py 95.86% <ø> (ø)
arviz/data/io_pystan.py 98.67% <ø> (ø)
arviz/plots/kdeplot.py 100.00% <ø> (ø)
arviz/plots/rankplot.py 91.89% <ø> (ø)
... and 4 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0c89fc3...da978db. Read the comment docs.

@OriolAbril OriolAbril mentioned this pull request May 14, 2020
Closed
@AlexAndorra
Copy link
Contributor

This looks really great, thanks @OriolAbril !
I'd be curious to work on it with you if you need help -- not before next week though.

Disclaimer: I'm close to a noob on doc generation, but this seems like a good time to understand how this works on ArviZ -- plus, I'd like to do something similar on PyMC3, where the stats docs would directly redirect to ArviZ to avoid inconsistencies.

@OriolAbril
Copy link
Member Author

Great! Thanks for the help! I can try to help with PyMC3 docs too.

Do you want to change anything else in the configuration? Otherwise we can merge and divide adding the references into several PRs

@AlexAndorra
Copy link
Contributor

AlexAndorra commented May 15, 2020 via email

@canyon289
Copy link
Member

I vote merging.

@canyon289
Copy link
Member

Alright its been a day. Merging this. We can figure out cross docs later! Thanks @OriolAbril

@canyon289 canyon289 merged commit 4db8674 into master May 18, 2020
@OriolAbril OriolAbril deleted the docs branch May 18, 2020 07:18
@OriolAbril OriolAbril mentioned this pull request May 18, 2020
Closed
9 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@OriolAbril @AlexAndorra @canyon289